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lypographical Conventions Used in this Publication 

Bold facing indicates what you should type. 
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Underlining is used for emphasis. 
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Information about this Manual 
Review the following items before you read this publication. 

The subject of this manual 

This manual explains what the WSORT program is and hov to execute WSORT. 

The audience for whom this publication was written 

This manual is for the user or system manager who needs to sort the 
contents of text files. Before you read this manual, you should complete 
the tutorials in either the WMCS USQllS. Introductory Manual or the WMCS 
System Manager ' s Introductory mniiSL- 

Related publications 

The chart on the following page lists other publications about the WMCS 
and the order in which they should be read. 
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Chapter 1 
General Information 



The WSORT program, one of the utilities in the WICS operating syston, 
sorts the contents of one or more files according to specified keys. 
WSORT can also merge the sorted files. 

This program is similar to the SORT program described in the WMCS User's 
Reference Manual. Unlike SORT, the switches and key modifiers in WSORT 
are written in the standard WMCS syntax. WSORT is faster and generally 
much easier to use than SORT. 



How WSORT works 



WSORT rearranges the contents of a file or files according to the 
criteria you specify. The sorted result is put into a destination file. A 
sort "key" is used to specify what information in the record should be 
compared with other records to sort that record. In a personnel list, for 
example, you can specify that the first key is the department number and 
that the second key is the salary. The sorted result is a list of 
employees ordered by salary within each department. If you do not specify 
a sort key, the entire record is used as the key. 

Records can be divided into fields. Fields give you the ability to 
describe how to find a key, when the exact position of the key in the 
record may vary. For example, the parts of an address may be separated on 
a line by commas. You can specify that a field is delimited by commas. 
This will enable you to sort the addresses by city name, which is 
somewhere after the second comma. The exact position of the sort key 
(city name) can be described for each record (address) by describing the 
field (after the second comma) it is in. 

Sort keys are specified with the :keylS^ switch. The "N" is a number from 
1 to 10 that determines the order the keys are used. "Modifiers" follow 
the equal sign in the switch. A key modifier describes the limits of a 
key. Submodifiers further pinpoint the location of the key. Key modifiers 
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for the :keyl^ switch are described in detail in chapter 2 of this 
manual. 



Hew to Execute the WSORT Program 



A summary of how to execute the WSORT command r useful for quick 
reference, is provided in the WMCS HsfiLla Reference Mann;^i . a complete 
description of executing the VISCBT program is given here. 



Parameters 

There are two required parameters. File List and Destination. They appear 
on the command line in the following order: 

> wsort filelist destination : switches 

The File List parameter specifies the names of the source files whose 
contents are to be sorted. It can contain several filenames separated by 
commas. Wildcard symbols are allowed in the File List parameter. 

The Destination parameter is a single file designation into which the 
sorted contents of the source files are merged and written. No wildcard 
symbols are allowed in this parameter. 



gwitches 

The following switches apply to the entire sort process and control how 
the files are sorted and how the records are treated. All switches allow 
unique abbreviations. Switches may appear in any order on the command 
line. 

These five switches are standard switches which affect the selection of 
files when wildcard symbols are used in the File List parameter: 



: before 



:since= 



:exclude= 



Files created or modified before the date and 
time you specify in this switch are included in 
the File List. 

Files created or modified since the date and time 
you specify in this switch are included in the 
File List. 

Files in the list you specif/ in this switch are 
excluded from the File List parameter. 
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:U1C= 



:mod 



Files cvmed by the UICs or usemames you specify 
in this switch are included in the File List. 

The modification date is used instead of the 
creation date in the :before= and :since= 
switches . 



These switches control how 
are displayed. 



files are sorted and how results of the sort 



;sort= 



:log 

: duplicates 



: stats 



;errorhandling= 



Files that match the wildcard symbols in the File 
List are read in the order you specify in this 
switch. Type extension^ uic, or date. The default 
is alphabetical order by filename. 

Names of the source files are logged to SYS$ERROR 
unless you specify :nolog. 

Records with duplicate key values are output 
unless you specify moduplicates. If 
rnoduplicates is specified, only the first record 
of several records with duplicate sort key values 
is written to the Destination file. 

Use this switch to display statistics about the 
sort to SYS$OUTPUT. The display includes the 
number of files sorted, the number of records 
sorted, the number of comparisons performed, the 
amount of memory used (in Kbytes) , and the amount 
of time used (in seconds) during the sort. 

This switch controls how erroneous records are 
handled. Six mutually exclusive options are 
available. No abbreviations are allowed. 

The default value is :error= reject. The values 
"report" and "stop" force the :log switch to 
":log" even if "molog" has been explicitly 
specified. 

Type one of the follcwing values for this switch: 

reject Do not report erroneous records and 
exclude than from the sort. 



stop Report the first erroneous 
then terminate. 



record and 
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report Report all erroneous records. If the 
:errorfile= switch is used, write the 
sorted erroneous records to that file. 

ignore Ignore erroneous records and do not 
report them. Sort them with the other 
records. If the :errorfile= switch is 
used, write the sorted erroneous records 
to that file. 

first Sort erroneous records as a group and 
write them at the top of the Destination 
file. If the :errorfile= switch is used, 
write the sorted erroneous records to 
that file. 



;errorfile= 



itext 



:recordlen= 



last Sort erroneous records as a group and 
write them at the bottom of the 
Destination file. If the :errorfile= 
switch is used, write the sorted 
erroneous records to that file. 

Use this switch to specify the name of a file in 
which the sorted erroneous records are placed. 
If the value of the :errorhandling= switch is 
"first," "last," "ignore" or "report," the sorted 
erroneous records are not written to the 
Destination file but are written to this "error" 
file. 

Source files are treated as text files unless you 
specify tnotext. A text file is a file of ASCII 
characters organized as lines of text. The ASCII 
<LF> character is the line terminator. A non- 
text file does not have the ASCII <LF> character 
as a line terminator and is organized solely as 
records with a fixed record length. 

Use this switch to specify the record size of 
non-text source and destination files, regardless 
of the actual file record sizes. lype a value 
from 1 to 65535 inclusive. 

If :recordlen= is specified and :text is not 
explicitly specified, or tnotext is specified, 
the files are read with the record length you 
specify in this switch. 

If rnotext is specified and :recordlen= is not 
specified, the record length used for all source 
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files is the actual 
source file. 



record length of the first 



:maxrecordlen= 



:memory= 



: ascending 
: descending 

:delimiter= 



:skip= 



Use this switch to specify the maximum length (in 
bytes) of any record in the source file list. If 
a text record is read which is longer than the 
value of this switch, an error is reported and 
WSORT terminates. The default is 
:maxrecordlerp=1024 . 

Use this switch to specify the maximum amount of 
monory (in Kbytes) to be used on the initial 
buffer allocation for sorting records. 

If files with fixed record lengths are sorted, 
the memory used will be 1 Kbyte more than the 
value specified by this switch. 

If text files with different length lines are 
sorted, the memory used will vary because of the 
nature of dynamic memory. However, the initial 
memory allocation will not be more than that 
specified in this switch. 

The more memory that is allocated to the WSORT 
utility for sorting records, the faster the sort 
will be. The default is :memory=64. 

Files are sorted in ascending order unless you 
specify : descending. 

Use this switch to sort files in descending 
order. This switch is mutually exclusive to the 
: ascending switch. 

Use this ^^itch to specify the characters which 
delimit fields within a record. This switch is 
only valid when used with the field= key 
modifier. (See chapter 2.) The value of the 
f ield= key modifier selects the field from which 
the sort key is extracted. Type a string of 
characters enclosed in double quotation marks. 
There are no default characters for this switch. 

Use this switch to specify the characters which 
are skipped when scanning a record for a key. 
Type a string of characters enclosed in double 
quotation marks. The default is 
: skip=<SP><TAB><LF> . 
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:ignoreleading= Use this switch to specify the leading characters 

which will be ignored when WSORT scans for a key 
within a field. lype a string of characters 
enclosed in double quotation marks. The default 
is : ignor eleading=<SP><TiB><LF> . 

:keyt^ Use this switch to specify sort keys upon which 

the sort is performed. The sort key order is 
specified by the value of N in the switch name, 
i.e., the primary sort key switch is :keyl=, the 
secondary sort key switch is :key2=, etc. Up to 
10 keys may be specified. This switch contains 
modifiers which describe the sort key 
characteristics. The key modifiers are described 
in detail in chapter 2 of this manual. 

All :key^^ switches must be numbered 
consecutively. For example, if you are using 
three sort keys, you must specify :keyl=, :key2=, 
and key3=. You cannot specify :keyl=, :key2=, and 
:key4= 

The order in which the tkeyNN switches appear on 
the command line does not matter. If there are no 
key switches specified, the entire record is used 
as the key and the comparisons are done as ASCII 
characters. 



Examples 

The following examples shew how various VISOBT switches can be used to 
sort text files. 

> wsort file.txt sorted.txt :descending 

Suppose this is the contents of FILE.TXT: 
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File name Logical/ Physical 



General Infonnation 



Created Usemame 



ALLOC. HLP.l 


2.5/ 


3.0 16-Apr-1985 00:00:00 SYSTEM 


ARCH.HLP.l 


5.8/ 


6.0 12-Oct-1985 00:00:00 SYSTEM 


ASai.HLP.l 


3.0/ 


3.0 12-Oct-1985 00:00:00 SYSTEM 


ASSIGN. HLP.l 


1.7/ 


2.0 12-Oct-1985 00:00:00 SYSTEM 


BACKUP. HLP.l 


3.2/ 


4.0 12-Oct-1985 00:00:00 SYSTEM 


BKQP.HLP.l 


1.3/ 


2.0 12-Oct-1985 00:00:00 SYSTEM 


B1UP. HLP.l 


3.0/ 


3.0 12-Oct-1985 00:00:00 SYSTEM 


CD.HLP.l 


1.4/ 


2.0 12-Oct-1985 00:00:00 SYSTEM 



WSORT sorts FILE. TXT in descending order and puts the result in the file 
SORTED. TXT. Ihis is the contents of SORTED. TXT: 



File name 


Logical/ 


Physical Created Usemame 


Directory listing of 


DSO/SYSHLP/ 




CD.HLP.l 


1.4/ 


2.0 12-Oct-1985 00:00:00 SYSTEM 


BTQP. HLP.l 


3.0/ 


3.0 12-Oct-1985 00:00:00 SYSTEM 


BKUP. HLP.l 


1.3/ 


2.0 12-Oct-1985 00:00:00 SYSTEM 


BACKUP. HLP.l 


3.2/ 


4.0 12-Oct-1985 00:00:00 SYSTEM 


ASSIGN. HLP.l 


1.7/ 


2.0 12-Oct-1985 00:00:00 SYSTEM 


ASai. HLP.l 


3.0/ 


3.0 12-Oct-1985 00:00:00 SYSTEM 


ARCH.HLP.l 


5.8/ 


6.0 12-Oct-1985 00:00:00 SYSTEM 


ALLOC. HLP.l 


2.5/ 


3.0 16-Apr-1985 00:00:00 SYSTEM 



> wsort file.txt sorted.txt :stats 

Suppose this is the contents of FILE.TXT: 



DEVICES. HLP.l 
CONFIG. HLP. 2 
COUNT. HLP.l 
DEF. HLP.l 
CRD.HLP.l 
CREATE.HLP.l 
DATES. HLP.l 
DEL. HLP.l 
DEALLOC. HLP.l 
CONFIG. HLP.l 
DEL. HLP. 2 
COPY. HLP.l 
DEV.HLP.l 
DEL.HLP.3 



SORTED.TXT. This is the contents of SORTED.TXT: 



3.6/ 


4.0 


12-Oct-1985 


00:00:00 SYSTEM 


1.7/ 


2.0 


13-Oct-1985 


08:03:12 SYSTEM 


1.8/ 


2.0 


16-Apr-1985 


00:00:00 SYSTEM 


l.V 


2.0 


12-Oct-1985 


00:00:00 SYSTEM 


1.8/ 


2.0 


16-;^r-1985 


00:00:00 SYSTEM 


1.5/ 


2.0 


12-Oct-1985 


00:00:00 SYSTEM 


4.5/ 


5.0 


12-Oct-1985 


00:00:00 SYSTEM 


2.0/ 


2.0 


16-Apr-1985 


00:00:00 SYSTEM 


1.8/ 


2.0 


16-Apr-1985 


00:00:00 SYSTEM 


1.7/ 


2.0 


12-Oct-1985 


00:00:00 SYSTEM 


2.0/ 


2.0 


16-Apr-1985 


08:07:35 SYSTEM 


3.4/ 


4.0 


12-Oct-1985 


00:00:00 SYSTEM 


1.7/ 


2.0 


16-Apr-1985 


00:00:00 SYSTEM 


2.0/ 


2.0 


16-Apr-1985 


09:14:27 SYSTEM 


;cendin 


g order < 


and puts the 


result in the file 
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CONFIG. HT.P.l 




1.7/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


CONFIG. HLP. 2 




1.7/ 


2.0 13-Oct-1985 


08:03:12 


SYSTEM 


COPY.HLP.l 




3.4/ 


4.0 12-Oct-1985 


00:00:00 


SYSTEM 


COUNT. HT.P.l 




1.8/ 


2.0 16-Apr-1985 


00:00:00 


SYSTEM 


CRD.HLP.l 




1.8/ 


2.0 16-Apr-1985 


00:00:00 


SYSTEM 


CREAl'E.HLP.l 




1.5/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


DATliS. HT.P.l 




4.5/ 


5.0 12-Oct-1985 


00:00:00 


SY3Tm 


DEALLOC. HT.P.l 




1.8/ 


2.0 16-Apr-1985 


00:00:00 


SYSTEM 


DEF. HT.P.l 




1.1/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


DEL. HT.P.l 




2.0/ 


2.0 16-Apr-1985 


00:00:00 


SYSTEM 


DEL.HT.P.2 




2.0/ 


2.0 16-Apr-1985 


08:07:35 


SYSTEM 


DEL.HT.P.3 




2.0/ 


2.0 16-Apr-1985 


09:14:27 


SYSTEM 


DEV. HT.P.l 




1.7/ 


2.0 16-Apr-1985 


00:00:00 


SYSTEM 


DE7ICF-S. HT.P.l 




3.6/ 


4.0 12-Oct-1985 


00:00:00 


SYSTEM 


The : stats switch 


displays 


the following report during the sort: 


1 file sorted 










14 records 


5 sorted 










52 comparisons performed 








22 Kbytes 


of memory used 








1 second of time 


used 









> wsort f ilel.txtffile2.txt, file3.txt sorted.txt :nodi:^icates 

Suppose this is the contents of FILE1.TXT: 



Directory listing of _DS0/SYSHLP/ 

File name Logical/ Physical 



Created 



ASCII. HLP. 1 
ASSIGN. HLP. 1 
BACKUP. HLP. 1 
ARCH.HLP.l 
BKUP.HLP.l 
ALLOC. HLP.l 
CD.HLP.l 
BTUP.HLP.l 



3.0/ 
1.7/ 
3.2/ 
5.8/ 
1.3/ 
2.5/ 
1.4/ 
3.0/ 



3.0 12-Oct-1985 
2.0 12-Oct-1985 
4.0 12-Oct-1985 
6.0 12-Oct-1985 
2.0 12-Oct-1985 
3.0 16-Apr-1985 
2.0 12-Oct-1985 
3.0 12-Oct-1985 



00:00:00 
00:00:00 
00:00:00 
00:00:00 
00:00:00 
00:00:00 
00:00:00 
00:00:00 



User name 

SYSTEM 
SYSTEM 
SYSTEM 
SYSTEM 
SYSTEM 
SYSTEM 
SYSTEM 
SYSTEM 



Suppose this is the contents of FILE2.TXT: 
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CD.HT.P.l 


1.4/ 


2.0 12-Oct-1985 


00:00:00 


SYSTM 


BTOP.HT.P.l 


3.0/ 


3.0 12-Oct-1985 


00:00:00 


SYSTEM 


BKUP.HLP.l 


1.3/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


BACKUP. HLP.l 


3.2/ 


4.0 12-Oct-1985 


00:00:00 


SYSTEM 


ASSIGN. Hli.l 


1.7/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


ASai.HT.P.l 


3.0/ 


3.0 12-Oct-1985 


00:00:00 


SYSTEM 


ARCH. HLP.l 


5.8/ 


6.0 12-Cct-1985 


00:00:00 


SYSTEM 


ALLOC.HLP.l 


2.5/ 


3.0 16-Apr-1985 


00:00:00 


SYSTEM 


Suppose this is 


the contents of F1LE3 


.TXT: 






FUNCTIONS. HLP.l 


1.8/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


DM.HLP.l ' 


1.5/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


EDITLIST. HLP.l 


1.8/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


DMNT.HT.P.l 


1.9/ 


2.0 12HDct-1985 


00:00:00 


SYSTEM 


DUMP.HF.P.l 


2.5/ 


3.0 12-Oct-1985 


00:00:00 


SYSTEM 


EPR.HT.P.1 


1.2/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


FILELIST. HLP.l 


1.8/ 


2.0 12-Oct-1985 


00:00:00 


SYSTEM 


FSTAT. HLP.l 


3.2/ 


4.0 16-Apr-1985 


00:00:00 


SYSTEM 


FPM3R.HLP.3 


1.8/ 


2.0 04-Mar-1985 


00:00:00 


SYSTEM 


DSTAT. HLP.l 


8.3/ 


9.0 12-Oct-1985 


00:00:00 


SYSTEM 


FIXSTACK. HLP.l 


1.5/ 


2.0 16-Apr-1985 


00:00:00 


SYSTEM 



All three files are sorted and the results are merged and put into the 
file SORTED. TXT. The :noduplicates switch suppresses the display of 
duplicate records in the sort. This is the contents of SORTED.TXT: 
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ALLOC. HLP.l 


2.5/ 


3.0 


16-Apr-1985 


00:00:00 


SYSTEM 


ARCH.HT.P.l 


5.8/ 


6.0 


12-Oct-1985 


00:00:00 


SYSTEM 


ASai. HLP.l 


3.0/ 


3.0 


12-Oct-1985 


00:00:00 


SYSTEM 


ASSIGN. HLP.l 


1.7/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


BACKUP. HF.P.l 


3.2/ 


4.0 


12-Oct-1985 


00:00:00 


SYSTEM 


BKUP.HT.P.l 


1.3/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


B1UP. HLP.l 


3.0/ 


3.0 


12-Oct-1985 


00:00:00 


SYSTEM 


CD.HT.P.l 


1.4/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


CHECKSUM. HLP.l 


1.9/ 


2.0 


16-Apr-1985 


00:00:00 


SYSTEM 


CHKD. HLP.l 


1.8/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


aP.HT.P.l 


1.4/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


CMD. HLP.l 


1.8/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


m.HT.P.l 


1.5/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


DMNT.HT.P.l 


1.9/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


DSTAT. HLP.l 


8.3/ 


9.0 


12-Oct-1985 


00:00:00 


SYSTEM 


DUMP. HLP.l 


2.5/ 


3.0 


12-Oct-1985 


00:00:00 


SYSTEM 


Directory listing of 


_DSO/sysHr.p/ 










EDITLIST.HT.P.l 


1.8/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


EPR. HLP.l 


1.2/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


FILELIST.HT.P.l 


1.8/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


FIXSTACK.HT.P.l 


1.5/ 


2.0 


16-Apr-1985 


00:00:00 


SYSTEM 


FPM3R.HLP.3 


1.8/ 


2.0 


04-Mar-1985 


00:00:00 


SYSTEM 


FSTAT.HT.P.l 


3.2/ 


4.0 


16-Apr-1985 


00:00:00 


SYSTEM 


FUNCTIONS. HT.P.l 


1.8/ 


2.0 


12-Oct-1985 


00:00:00 


SYSTEM 


File name 


Logical/ 


Physical 


Created 


Usemame 



For examples of the :keyN= switch, read chapter 2 of this manual. 
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Chapter 2 
WSORT Key Modifiers 



This chapter explains the key modifiers that can be used with the :keylt= 
switch for WSORT. Key nxDdifiers allow you to perform complicated sorts 
with custom-made keys. If you do not use the :keyN= switch, the entire 
record is used as the key and the comparisons are done as ASQI 
characters. 

As many as ten :keyN= switches can be typed on the command line. (N is a 
number from 1 to 10.) The value of N determines the sort key order. For 
example, :keyl= is the primary sort key, :key2= is the secondary sort 
key, etc. All rkeyt^ switches must be numbered consecutively. Hcwever, 
they can be typed in any order on the command line. 

Key modifiers are typed after the equal sign and are separated by commas. 
They can appear in any order. For example: 

> wsort file.txt sorted.txt :keyl=delimiter=" ",field=l, dictionary 

Unique abbreviations of the modifiers are allowed. For example, "asc" for 
ascending, "die" for dictionary, "f" for floatingpoint, etc. 

Key modifiers override WSORT switches and default values with similar 
names. For example, ":keyl=ascending" overrides the "rdescending" switch 
on the command line. 



Direction Modifiers 



The following mutually exclusive modifiers specify the direction of the 
sort for a single sort key. 
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ascending Use this modifier to specify that the key will 

sort in ascending order. 

descending Use this modifier to specify that the key will 

sort in descending order. 



Field Modifiers 



Sort keys can be used to divide a record into fields. Fields can be 
defined in a very flexible manner using key modifiers. A sort key is 
extracted from a field based upon the modifiers and data type of the key. 

Field definition can be as simple as specifying an absolute location in a 
record, or as complex as isolating a free-format, anywhere- in- the- record 
field based upon the data in a record. 

The following sample file record will be used to illustrate the operation 
of field modifiers. Results of each field definition example will be 
enclosed in double quotation marks in order to make spaces easier to see. 
The sample record is a single line from the display of this DIR command: 

> dir * :size : create rusemame :head 

The sample record is printed belcw in boldface. The numbers above the 
sample line represent the relative byte positions. 

11111111112222222222333333333344444444445555555555666666 
12345678901234567890123456789012345678901234567890123456789012345 

SORT. C. 242 85.4/ 86.0 23-Oct-1985 10:24:57 GB 



The following modifiers govern the extraction of a single sort key from a 
record: 

startat= Use this modifier to specify (by byte position) 

where the field scan will start, relative to the 
beginning of the record. Any data before that 
specified by this modifier will not be examined 
when the fields are defined. This modifier can 
have positional submodifiers. The default is 
"startat=l" (the first byte in the record) . 
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Suppose you typed this key modifier: 
: keyl=startat=36 

This defines the following part of the sample 
record as the key field: 

" 86.0 23-Oct-1985 10:24:57 GB" 

endat=n Use this modifier to specify (by byte position) 

where the field scan will end, relative to the 
iDeginning of the record. Any data after that 
specified by this modifier will not be examined 
when the fields are defined. This modifier can 
have positional submodifiers. The default is the 
end of the record. 

Suppose you typed this key modifier: 

:keyl=endat=15 

This defines the following part of the sample 
record as the key field: 

"SQRT.C.242 

Suppose you typed this key modifier: 

: keyl=startat=24 , endat=30 

This defines the following part of the sample 
record as the key field: 

" 85.4" 



Skipp= Use this modifier to specify the characters to 

skip when parsing a key from a text record, lype 
a string of characters enclosed in double 
quotation marks. When a "field=" modifier is 
specified for a sort key, the characters 
specified by this modifier are skipped before the 
search for a character specified by the 
:delimiter= switch. The default is the value of 
the : skips switch. 
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Suppose you typed this key modifier: 

: keyl=startat=24 , endat=3 , skip= " " 

This defines the follcwing part of the sample 
record as the key field: 

"85.4" 



delimiter= Use this modifier to specify the characters which 

delimit fields in a text record. Ihe value of 
this modifier is a string of characters enclosed 
in double quotation marks. When a "field=" 
modifier is specified for a sort key, the 
characters specified by this modifier are used to 
divide the record into fields. Since delimiters 
can be in different places relative to the 
beginning of a record for different records, 
fields can vary in size and number. The default 
is the value of the ":delimiter=" switch. 

Suppose you typed this key modifier: 

:keyl=delimiter=". :/" 

This divides the sample record into eight fields. 
Note that the delimiter characters are not part 
of the fields. (The sample fields are enclosed in 
double quotation marks.) 



85" 



field 1 = 


"SORT" 


field 2 = 


"C" 


field 3 = 


"242 


field 4 = 


"4" 


field 5 = 


86" 


field 6 = 


"0 23-Oct-1985 10" 


field 7 = 


"24" 



field 8'= "57 GB" 

Because delimiter characters are not contained in 
fields, it is possible to have a field with a 
length of zero bytes created fcy two adjacent 
delimiters. This is known as an "empty" field. 
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Suppose you typed this key modifier: 

: keyl=startat=54 , endat=63 , del iraiter= " : " 

This divides the sample record into five fields: 

field 1 = "" (Qirpty field) 

field 2 = "10" 

field 3 = "24" 

field 4 = "57" 

field 5 = "" (empty field) 

Any character specified by the "delimiter^" 
modifier can not appear in the "ignoreleading" 
modifier for the same sort key definition. 



field= Use this modifier to specify which field the key 

resides in. The first field in a record is 1, the 
second field is 2, etc. There is no default value 
for this modifier. Therefore, a record is not 
divided into fields unless this modifier is 
explicitly specified, even if the "delimiter=" 
modifier is specified. 

Suj^se you typed this key modifier: 

: keyl=startat=54 , endat=63 , \ 
delimiter=" :",field=2 

This defines the following part of the sample 
record as the key field: 

"10" 

Since the number of fields in a record can vary, 
any record which divides into fewer fields than 
is specified by this modifier ' results in an 
erroneous record. Selection of an anpty field by 
this modifier also results in an erroneous 
record. The disposition of an erroneous record is 
specified by the :errorhandling= switch. 



length= Use this modifier to place an absolute limit (in 

bytes) on the field length. There is no default 
length. If no length is specified, it is 
determined by the other modifiers. This modifier 
can have length submodifiers. 
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offset= 



Suppose you typed this key inodifier: 

: keyl=startat=24 , endat=3 , length=5 

This defines the following part of the sample 
record as the key field: 

" 85" 

Suppose you typed this key modifier: 

:keyl=length=19 

This defines the following part of the sample 
record as the key field: 

"SORT. C. 242 

Use this modifier to specify where the key 
starts, relative to the beginning of a field. 
This modifier can use positional submodifiers. 
The default is "offset=0". 

Suppose you typed this key modifier: 

: keyl=length=25 , of f set=5 

This defines the following part of the sample 
record as the key field: 

"C.242 85.4" 

Suppose you typed this key modifier: 

: keyl=del imiter= "/ " , f ield=2 , of f set=-7 , \ 
length=6 

This defines the following part of the sample 
record as the key field: 

" 85.4" 



ignoreleading= 



Use this modifier to speci:fy the leading 
characters which are ignored when extracting the 
key from a field. lype a string of characters 
enclosed in double quotation marks. Characters 
are ignored starting from the offset from the 
beginning of the field until the first non- 
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ignorable character is encountered. The default 
value is the value specified by the 
:ignoreleading= switch. 

Suppose you typed this key modifier: 

:keyl=startat=24,endat=32, ignoreleading=" " 

This defines the following part of the sample 
record as the key field: 

"85.4/ " 

Suppose you typed this key modifier: 

: keyl=del iiff= "/ " , f ield=2 , of f =-7 , len=6 , ignor el 
eading=" " 

This defines the following part of the sample 
record as the key field: 

"85.4" 

Any character in the "ignoreleading=" modifier 
cannot appear in the "delimiter=" modifier for 
the same sort key definition. 



Field Suisnodif iers 



Positional submodifiers are used for specifying the value of the 
"startat=", "endat=", "length=" and "offsets" key modifiers. If more 
than one positional submodifier is used, they must be separated by commas 
and enclosed in double quotation marks. For example: 



^A" 



: keyl=startatr="byte=2 ,bit=4 

Positional submodifiers specify a relative position, i.e., 1 means the 
first, 2 means the second, etc. There are eight different submodifiers. 

(number) This submodifier is a number which implies the 

relative fcyte position. The following positional 
submodifier specifies that the field starts at 
the 17th byte of a record: 

startat=17 
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bcddigits= 
bits= 



This submodifier is a synonym for "nibbles=". 



This submodifier specifies the relative bit 
position. The following positional submodifier 
specifies that the key offset starts at the 5th 
bit from the beginning of the field: 

offset=bits=5 

The following examples are all equivalent: 

startat=bits=17 
startat=bytes=3 
startat=3 



bytes= 



This submodifier specifies the relative byte 
position. A byte is 8 bits. The following 
positional submodifier specifies that the field 
ends in the 32nd byte of a record: 

endat=by tes=3 2 



characters^ 
doubl0vords= 



This submodifier is a synonym for "bytes=' 



This submodifier specifies the relative 
doubla^ord position. A doubleword is 32 bits. 
There are four bytes per doubleword. The 
following positional submodifier specifies that 
the key offset starts at the 2nd doublevord from 
the beginning of the field: 

of f set=doubl ewor d=2 

The following submodifier specifies the same 
relative position: 

offset=bytes=5 



nibbles^ 



This submodifier specifies the relative nibble 
position. A nibble is 4 bits. There are two 
nibbles per byte. The following submodifier 
specifies that the field starts at the 3rd nibble 
of a record: 
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star tat=nibbl es=3 



The follcwing submodifier specifies the same 
relative position: 

startat=bytes=2 



words= This submodifier specifies the relative word 

position. A word is 16 bits. There are two 
bytes per word. The follcwing submodifier 
specifies that the field ends at the 6th word of 
a record: 

endat=words=6 

The follcwing example specifies the same relative 
position: 

startat=bytes=ll 



If several positional submodifiers are used together, they are relative 
to each other, with the first being relative to the beginning of the 
record. The follcwing sets of equivalent examples illustrate the 
relativity. The final position is marked with an asterisk in the 
"record" line. 

startat="doublevords=l ,words=l ,bytes=l ,nibbles=l ,bits=l" 

startat= "wor d=l , bit=l " 

startat=byte==l 

startat=l 



Record 


1 * 






Doublewords 


1 1 






Words 


1 1 




2 


Bytes 


1 1 


2 


1 3 



2 I 3 

3 14 15 16 

5 I 6 I 7 I 8 I 9 I 101 111 12 



startat= "doubleivords=2 ,words=2 ,bytes=2 ,nibbles=2" 
startat= 'Vor d=4 , bit=13 " 
star tat=nibbl es=16 



Record 

Doubleyords 

Words 

Bytes 

Nibbles 



1 12 13 

1 12 13 14 15 16 

1I2I3I4I5I6I7I8I9I10I11I12 

I I I I I I I i I I I I I I I I I I I I I I I 
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startat= "doublewords=4 ,bytes=-l ' 
startat= "words=5 ,fciytes=4 " 
startat=12 



Record 


1 


















* 


Doublewords 


1 1 








1 2 








1 3 




Words 


1 1 




2 




1 3 




4 




5 


1 6 


Bytes 


1 1 


2 


3 


4 


1 5 


6 


7 


8 


9 


101 111 12 



Length submodifiers are the same as the positional submodif iers, but the 
values for length submodifiers are additive instead of relative. The 
following sets of equivalent examples illustrate the addition. The final 
length is marked with an arrow in the "length" line. 

Length= "doubl€words=l , words=l , bytes=l " 
Length= "wor d=3 , by tes=l " 
Length=bytes=7 



Length=7 



Length 
Doublewords 
Words 
Bytes 



1 I 2 

1 12 13 14 

1I2I3I4I5I6I7 



•> 



I 3 

15 16 

8 I 9 I 101 111 121 



Length="doublewords=2 ,words=-2 ,bytes=2 ,nibbles=2" 

Length= "wor ds=4 , by tes=-l " 

Length=bytes=7 

Length=nibbl es=l 4 

Length=7 



Length 

Doublewords 

Words 

Bytes 

Nibbles 



-> 



1 12 13 

1 12 13 14 15 16 

1 I 2 I 3 I 4 I 5 I 6 I 7 I 8 I 9 I 101 111 12 

I I I I I I I I I I I I I I I I I I I I II I 



Length= "doubl ewor ds=3 , bytes=-l " 
Length= "wor ds=5 , by tes=l " 
Length=ll 



Length 
Doublewords 
Words 
Bytes 



2 

3 I 4 



I 4 
6 I 7 



I 8 



101 111 12 
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Data. Type Modifiers 



The follaving key modifiers specify the data type of a single sort key. 

These can further refine the value of the sort key after it has been 

extracted from a field. There are thirteen data types used by the WSOPT 
utility. Each is mutually exclusive with the others. 

The following sample file record will be used to illustrate the operation 
of data type modifiers. The sample record is a single line from the 
display of this DIR command: 

> dir * :size tcreate rusemame :head 

The sample record is printed belcw in boldface. The numbers above the 
sample line represent the relative fcyte positions. 

11111111112222222222333333333344444444445555555555666666 
12345678901234567890123456789012345678901234567890123456789012345 

SCRr.C.242 85.4/ 86.0 23-Oct-1985 10:24:57 GB 



The following modifiers govern the extraction of a single sort key from a 
record: 



ascii Use this modifier to specify the sort key data 

type as ASCII (8-bit unsigned byte) characters. 
This is the default data type when a data type 
modifier is not specified. This data type does 
not further modify the sort key as defined by the 
field definition modifiers. 



asciidecimal Use this modifier to specify the sort key data 

type as an ASCII decimal number. A plus, +, or a 
minus, -, sign can appear immediately before the 
first numeric character. The key value is 
converted to a signed 32-bit binary integer for 
comparison. Any leading spaces or tabs are 
skipped when scanning the field for the ASCII 
decimal number. This is in addition to those 
specified by the "ignoreleading=" modifier. 
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Suppose you typed this key modifier: 

: keyl=del= V " , f ield=2 , of f=-7 , len=6 , \ 
asciidecimal 

This defines the following integer value from the 
sample record as the sort key: 

85 



asciifloatingpoint Use this modifier to specify the sort key data 

type as an ASCII floating-point number. A plus or 
a minus sign can appear immediately before the 
first numeric character. The number can be in 
fixed point (x.xx) or scientific (x.xxExx) 
notation. The key value is converted to a signed 
64-bit binary floating-point number for 
comparisions. Any leading spaces or tabs are 
skipped when scanning the field for the ASCII 
floating-point number. This is in addition to 
those specified by the "ignoreleading=" modifier. 

Suppose you typed this key modifier: 

:keyl=del="/", f ield=2 rof f=-7 ,ler^6 ,asciif loa 
tingpoint 

This defines the following floating-point value 
from the sample record as the sort key: 

85.4 



asciihexadecimal Ihis modifier specifies the sort key data type as 

an ASCII hexadecimal number. A dollar sign, $, 
can appear immediately before the first 
hexadecimal character. Uppercase or lowercase 
characters can be used as hexadecimal digits. 
The key value is converted to a signed 32-bit 
binary integer for comparision. Any leading 
spaces or tabs are skipped when scanning the 
field for the ASCII hexadecimal number. This is 
in addition to those specified by the 
"ignoreleading=" modifier. 



2-12 



WSORT Key Modifiers 



Suppose you typed this key modifier: 

: keyl=del= "/ " , f ield=2 , of f=-7 , len=6 , asciihexa 
decimal 

This defines the following integer value (base 
10) from the sample record as the sort key: 

133 (85 in base 16) 



asciireal 
binary 



This is a synonym for "asciifloatingpoint". 



Use this modifier to specify the sort key data 
type as a signed binary integer. The default 
length of the binary data type is four bytes. 



bitfield 



Use this modifier to specify the sort key data 
type as an unsigned bit field. It can be from 1 
to 32 bits in length and does not need to begin 
or end on byte boundaries. The default length of 
a bit field is 32 bits. 



easel ess 



This modifier is the same as "ascii" except that 
no distinction is made between uppercase and 
lowercase alphabetic characters during 
comparisons. If two records have the same key 
value, their order is determined by comparing the 
original fields as ASCII characters. 



dictionary 



Use this modifier to specify the sort key data 
type as alphanumeric. All alphanumeric 
characters in the field form the value of the 
key. If two records have the same key value, 
their order is determined by comparing the 
original fields as ASCII characters. 
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Suppose you typed this key modifier: 

:keyl=deliiniter=" " , f ield=l , dictionary 

This defines the following part of the sample 
record as the value of the sort key: 

"sortc242" 



floatingpoint 



Use this modifier to specify the sort key data 
type as a signed binary floating-point number. 
The length of the floating-point number can be 
either four bytes (32 bits) or eight bytes (64 
bits) . Ihe floating point format conforms to the 
IEEE floating-point standard. 



location 



Use this modifier to specify the sort key data 
type is actually the location of the key in the 
record. Ihe location is relative to the beginning 
of the record. 

Suppose you typed this k^ modifier: 

: keyl=del:= V " , f ield=2 , of f=-7 , len=6 , \ 
ign=" ", location 

This defines the following binary integer value 
from the sample record as the sort key: 

27 



real 
width 



This modifier is a synonym for "floatingpoint". 



Use this modifier to specify the sort key data 
type is actually the width, or length, of the 
field in the record. 
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Suppose you typed this key modifier: 

: keyl=del= "/ " , f ield=2 , of f =-7 , len=6 , 
ign=" ", width 

This defines the following binary integer value 
from the sample record as the sort key: 



Miscellaneous Modifiers 



The following modifiers perform miscellaneous functions for a single sort 
key. 

allowerrors Use this modifier to specify whether or not a 

record is marked erroneous if an error occurs 
while extracting the sort key. The default is 
"noallcwerrors", which marks a record as 
erroneous if an error occurs during sort key 
extraction. 

ignoreleading Use this modifier to specify whether or not 

leading characters are ignored when extracting a 
sort key from a record field. This modifier can 
override the value specified by the 
: ignoreleading= switch and cause leading 
characters to not be ignored when extracting a 
key from a field. 

Note that this modifier is different from the 
"ignoreleading=" valued modifier. The default 
value of this modifier is "ignoreleading". This 
allows the file default to be applied to the sort 
key if no "ignoreleading=" modifier has been 
specified. 
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We are constantly improving our documentation, and we welcome scecific comments on mis manual 

Document Title: . 

Part Numfaen ^ 



What would you delete from the manual and wny? 



What areas need greater amphasis? 



List any terms or symbols used incorrectly. 



Your Position: D Novice user D System manager 

D Experienced user Q Systems analyst 

D Applications programmer D Hardware technician 

Questions and Comments Page Na 

Bnefty describe examples, illustrations, or information that you think should be added 
to this manual. 
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